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LiveCode Builder Style Guide 


Introduction 


This document describes best practices to be followed when working with LiveCode Builder source code. Please 
follow it especially when writing code to be included with the main LiveCode product package. 


Copyright headers 


Please include a license header at the top of the .icb file. 


For the main LiveCode repository, or for any community extensions, the license is the GNU General Public License 
v3 without the "any later version" clause. 


Naming 


Module name 


The module name uses reverse DNS notation. For example, a module created by the Example Organization would 
use module names beginning with org.example . 


Replace any hyphen ( - ) characters in a domain name with underscore (__ ) characters. For example, a module 
derived from the £izz-buzz .example.org domain could be Org .cxanplecrazz souizZ|. 


Additionally, add an underscore (__ ) to the start of any element in the domain name starting with a digit. For 
example, a module derived from the 999.example.org domain could be org.example. 999. 


You must only use module names corresponding to domain names that you control or are allowed to use. This 
restriction is enforced by the the LiveCode extension store. 


If you don't have a domain name of your own, you may use module names beginning 

with community. livecode.<username> , replacing <username> with the username you use to log into the LiveCode 
extension store. For example, if your username is "sophie", then you can create a module 

named community.livecode.sophie.mymodule . 





For the main LiveCode repository, please use module names beginning with com.livecode . 


Always write module names in lower case. 


Naming variables and parameters 


Give variables and parameters xcamelCaseNames with a leading lowercase character indicating their scope and 
availability. 


The meanings of the leading lowercase characters are: 
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Prefix Context Meaning 

k all constant 

Ss module static variable 

m widget static variable 

p handler definitions in argument 

r handler definitions out argument 

x handler definitions inout argument 
t handler bodies local variable 


In general, please use nouns to name your variables and parameters. Make the names descriptive; for example: 


variable tOutputPath as String -- Good 
variable tString as String -- Bad 


For Boolean variables, please try to use "yes or no" names. For example: 


variable tIsVisible as Boolean 


variable tHasContents as Boolean 


Naming handlers 
Give handlers camelCase names. 


Use verbs to name your handlers. For example, 


handler rotateShape(inout xShape, in pAngleInDegrees) 


end handler 


Naming types 
Give types Titlecase names. 


To distinguish from handlers, use nouns to name your types. For example, 


type RotationAngle is Number 
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Documenting the source code 


In-line documentation for a definition is extracted from a /** */ comment block immediately before the start of the 
definition. 


Always add a top-level documentation block at the start of the LCB file describing your widget, library or module. In 
addition, add in-line documentation to all of the following: 


syntax definitions 

property definitions 

public handler definitions in libraries and modules 
public variable definitions in modules 


It is particularly important to add documentation to all syntax and to any public handlers that aren't primarily 
accessed using syntax. 


Additionally, add documentation for all messages that are posted by a widget. The documentation for each message 
must be placed in the top-level documentation block for the widget. For example: 


/* 
The navigation bar widget is intended for use in mobile apps for 
switching between cards, although there are many other possible 


uses. 


Name: hiliteChanged 

Type: message 

Syntax: on hiliteChanged 

Summary: Sent when a navigation item is selected 


=) 
widget com. livecode.widget.navbar 


end widget 


Please refer to the Extending LiveCode guide for full details of the syntax of in-line documentation comments, 
including examples. 


Named constants 


Often, it is useful to use constant values in your code. Please declare named constants rather than placing the 
values in-line. For example, you may want to create three tabs labelled "Things", "Stuff", and "Misc": 
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constant kTabNames is ["Things", "Stuff", “Mise™] 


handler createTabs () 
variable tName 
repeat for each element tName in kTabNames 
-- Create the tab 
end repeat 


end handler 


In particular, please avoid any "magic numbers" in your code. 


Whitespace 


Indentation 

Please indent with tab characters. Use one tab character per level of indentation. 
Please do not use a level of indentation at module level. 

Comments should be indented to the same level as the code they apply to. 


For example: 





module org.example.indent 


-- Example handler 
handler fizzBuzz(in pIsFizz) 
if pIsFizz then 
return: Whazz! 
else 
-- Maybe this should have a capital letter 
return "buzz" 
end if 


end handler 





end module 


If it's necessary to mix spaces and tabs for indentation, please use 3 spaces per tab. 


Wrapping 


Avoid lines longer than 80 characters. Break long lines using a \ continuation character. Indent continuation lines 


by two levels. For example: 
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CGomenecine hivercolbaicie ak [Mei Weeney. Mike, Wilskeic’, Welasie, Wake Minmevein'?. \ 





"more", "readable", "when", "wrapped", "nicely"] 


When breaking a handler definition or handler type definition, break long lines at commas: 


handler processStringAndArray(in pStringArg as String, \ 


in pArrayArg as Array) returns Boolean 


Handler declarations, definitions and calls 


In handler definitions and handler type definitions, don't insert whitespace between the handler name and the 
parameter list. For example: 


handler type Fizzer () -- Good 





handler type Buzzer () -- Bad 


In handler parameter lists, please add a space between each parameter. For example: 


handler formatAsString(in pValue, out rFormat) -- Good 











handler isEqualTo(in pLeft,in pRight) -- Bad 


Please observe the same formatting in handler calls. For example: 


variable tFormatted 
variable tIsEqual 
formatAsString(3.1415, tFormatted) -- Good 








isEqualTo (tFormatted,"3.1415") into tIsEqual -- Bad 





List and array literals 


In list and array literals, please add a space between each element, after the comma. For array literals, also insert 
space between key and value, after the colon. For example: 


constant kPowersOfTwo is [1, 2, 4, 8] 
constant) kBordendwalcelis s4sim dents © Osa Ol ue Orth © Muss O yee inulec vin tote ll eer tonTe Cy I eauel cae 


Widget-specific guidelines 
This section contains recommendations that are specific to writing widgets. 


As a general rule, try to minimize surprise for users who mix widgets with classic LiveCode controls by using similarly 
named events and properties with similar semantics. 
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Writing load handlers 


When writing an onLoad() handler to initialise a widget from serialised state: 


e Always call property setters to update the widget state. Do not set instance variables directly. 

¢ Always check that the property array contains each key rather than accessing it unilaterally. 

e If keys are absent from the property array, do not set them to default values. Rely on the oncreate() handler to 
have already done that. 


Example: 


public handler onLoad(in pProperties) 
if "showBorder" is among the keys of pProperties then 
setShowBorder (pProperties["showBorder"] ) 
end if 
if "opaque" is among the keys of pProperties then 
setShowBackground (pProperties ["opaque"] ) 
end if 


end handler 


Classic control properties 


Where possible, try to make the names and effects of widget properties as similar as possible to properties of classic 
controls. For example: 


e label: the text for the primary text label 
e showBorder: whether to display an outline 
e opaque: whether to fill in the background 


Host control properties 


When relying on properties that are implemented by the widget host control, such as the classic color and pattern 
properties, include metadata definitions to display them in the Pl, but do not include a property definition. 


Because there is no property definition, the documentation for the host control property must be placed in the top- 
level documentation block comment before the start of widget definition. 


For example, to shadow the bordercolor host control property: 
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Test widget that demonstrates shadowing the 


<borderColor (property) > property. 


Name: borderColor 


VOCs PEOPEEEY, 


Syntax: set the borderCol 
Syntax: get the borderCol 





lor of <widget> to <color> 
lor of <widget> 


Summary: Color for drawing circular outline 


Description: 


the <borderColor> property controls the colon used to draw the 


widget's outline. 


my 


widget org.example.host_control property 


metadata borderCo 
metadata borderCo 
metadata borderCo 


metadata borderCo 


end widget 


Events 


Always implement: 


e* onCreate() 
e onSave() 
e onlLoad() 


e onPaint () 
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is 





ALONE 


or. 


.section 


label 


is 


is 








1 OuS 


.default 


You should usually implement: 


e onGeometryChanged() : if you have any non-trivial recomputation required to handle resizing 
e¢ onMouseDown() / onMouseUp() / onMouseMove() : alwayS post these to script in order to behave like a classic 


control 
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